<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>Creating Skeletons and skins</title>
<link rel="stylesheet" href="doc.css" type="text/css" />
</head>
<body>
<div class="document">
<div class="navigation navigation-header container">
<span class="previous">Previous: <a class="reference" href="skeletal_animations.html" title="Skeletal Animations">Skeletal Animations</a></span><span class="next">Next: <a class="reference" href="animations.html" title="Animations">Animations</a></span><span class="breadcrumbs"><a class="reference" href="index.html" title="Programming Guide">Programming Guide</a> » <a class="reference" href="skeletal_animations.html" title="Skeletal Animations">Skeletal Animations</a> » Creating Skeletons ...</span></div>
<h1 class="title">Creating Skeletons and skins</h1>

<div class="section" id="the-skeleton-file">
<h1><a class="toc-backref" href="#id195">The skeleton file</a></h1>
<p>Skeletons are defined in .py files. The first thing you will do is create the
root bone for your skeleton. Here we create what is going to be the body of our
human skeleton as follows:</p>
<p>doc/programming_guide/skeleton/root_bone.py:</p>
<pre class="py-doctest">
<span class="py-keyword">from</span> cocos.skeleton <span class="py-keyword">import</span> Bone, Skeleton

root_bone = Bone(<span class="py-string">'body'</span>, 70, -180.0, (0.00, 0.00))

skeleton = Skeleton(root_bone)</pre>
<p>This reads like: Create a bone labeled 'body' that is 70 pixels long, is
rotated by -180 degrees and starts on (0,0). We rotate the bone because we want
to be able to move its shoulders and not its legs, so the fixed part of the
skeleton will be its waist, ie, the origin of the root bone.</p>
<p>You can see the skeleton you have created using with a small piece of code.</p>
<p>from doc/programming_guide/skeleton/show_root_bone.py:</p>
<pre class="py-doctest">
<span class="py-keyword">from</span> cocos <span class="py-keyword">import</span> skeleton

<span class="py-comment"># import the skeleton we have created</span>
<span class="py-keyword">import</span> root_bone

<span class="py-keyword">class</span> <span class="py-defname">TestLayer</span>(cocos.layer.Layer):
    <span class="py-keyword">def</span> <span class="py-defname">__init__</span>(self):
        super( TestLayer, self ).__init__()

        x,y = director.get_window_size()

        <span class="py-comment"># create a ColorSkin for our skeleton</span>
        self.skin = skeleton.ColorSkin(root_bone.skeleton, (255,0,0,255))

        <span class="py-comment"># add the skin to the scene</span>
        self.add( self.skin )
        x, y = director.get_window_size()
        self.skin.position = x/2, y/2</pre>
<p>It will look like this:</p>
<div class="figure">
<img alt="skeleton/show_root_bone.png" src="skeleton/show_root_bone.png" />
</div>
<p>The important new concept here is the skin. Skins are responsible for drawing
the skeletons. Here we use the basic skin, ColorSkin, that just draws a colored
line over the bone. A skin, like everything else, is just a cocosnode, so you
can add it to your node to place it on screen.</p>
</div>
<div class="section" id="the-skin-file">
<h1><a class="toc-backref" href="#id196">The skin file</a></h1>
<p>Now, we want to skin this skeleton with some images, so we create a skin file.
The skin file will look like this:</p>
<p>doc/programming_guide/skeleton/root_skin.py:</p>
<pre class="py-doctest">
skin = [
    (<span class="py-string">'body'</span>, (25, 91), <span class="py-string">'gil-cuerpo.png'</span>, True, True, 0.5),
  ]</pre>
<p>This reads like: This skin ha an image for the bone labeled 'body', this image
has an offset of (25, 91) from the bone origin, the image file is
'gil-cuerpo.png' (provided by cocos), its flipped on its x axis, its flipped on
its y axis (remember we rotated the bone by -180), and its scaled to half its
size.</p>
<p>Now we can show the skeleton with the skin we have just created.</p>
<p>from doc/programming_guide/skeleton/show_root_skin.py:</p>
<pre class="py-doctest">
<span class="py-comment"># import the skeleton we have created</span>
<span class="py-keyword">import</span> root_bone
<span class="py-keyword">import</span> root_skin

<span class="py-keyword">class</span> <span class="py-defname">TestLayer</span>(cocos.layer.Layer):
    <span class="py-keyword">def</span> <span class="py-defname">__init__</span>(self):
        super( TestLayer, self ).__init__()

        x,y = director.get_window_size()

        <span class="py-comment"># create a ColorSkin for our skeleton</span>
        self.skin = skeleton.BitmapSkin(root_bone.skeleton, root_skin.skin)

        <span class="py-comment"># add the skin to the scene</span>
        self.add( self.skin )
        x, y = director.get_window_size()
        self.skin.position = x/2, y/2</pre>
<p>It will look like this:</p>
<div class="figure">
<img alt="skeleton/show_root_skin.png" src="skeleton/show_root_skin.png" />
</div>
</div>
<div class="section" id="the-skeleton-editor">
<h1><a class="toc-backref" href="#id197">The skeleton editor</a></h1>
<p>At this point, we can use the first tool provided, the skeleton editor. You start
the editor like this:</p>
<pre class="py-doctest">
tools$ python skeleton/skeleton_editor.py ../doc/programming_guide/skeleton/root_bone.py ../doc/programming_guide/skeleton/root_skin.py</pre>
<p>It will look like this:</p>
<div class="figure">
<img alt="skeleton/root_editor.png" src="skeleton/root_editor.png" />
</div>
<p>There you can see the skin part of your skeleton and several control points.
Control points can be dragged. If a control point is on top of another control
point, you can change your selection using the scroll weel. The current control
point has a small halo.</p>
<p>In this example you can see the red control point, which controls the rotation
of the bone, the two blue control points, which control the position of the
bone and skin part, and the green control point (behind one of the blue ones)
which controls the skeleton position.</p>
<p>Pressing 's' will save the changes you have made to the skeleton and skin file. This
will overwrite the .py files, so b carefull to just pur the data of the skeleton
and skin in this files.</p>
<p>This is a helpfull tool in creating your skins, as the only way to know the real
offsets between your skeleton parts and the image the artist has creates is
visually.</p>
<p>Now we add more bones and skin parts to the skeleton. Bones, other than the root
bone, are attached to other bones and thei position and rotation are relative to
its parent bone position and rotation.</p>
<p>doc/programming_guide/skeleton/body_and_arm.py:</p>
<pre class="py-doctest">
<span class="py-keyword">from</span> cocos.skeleton <span class="py-keyword">import</span> Bone, Skeleton

<span class="py-keyword">def</span> <span class="py-defname">Point2</span>(*args): <span class="py-keyword">return</span> args

root_bone = Bone(<span class="py-string">'body'</span>, 70, -180.0, Point2(0, 0)).add(
    Bone(<span class="py-string">'upper_arm'</span>, 30, 120, (0, -70)).add(
        Bone(<span class="py-string">'lower_arm'</span>, 30, 30, (0, -30))
    )
)

skeleton = Skeleton(root_bone)</pre>
<p>Here we abuse the fact that the function 'add' returns the parent bone, so
you can chain call to add and have and indentation that resembles the
hierarchical structure of the skeleton.</p>
<p>The upper arm is 30 pixels long and is placed at the end of the body by offsetting
if -70 pixels. The lower
arm is also 30 pixels long and is also placed at the end of its parent, the upper
arm. Bone length doesnt affect the transofrmations or placement of other bones,
but it useful to see what you are creating.</p>
<p>The skeleton we have just created looks like this:</p>
<div class="figure">
<img alt="skeleton/body_and_arm.png" src="skeleton/body_and_arm.png" />
</div>
<p>Now we add the skin. We wont care about the positions or flipping, as we will
be changing that parameters when looking at it.</p>
<p>doc/programming_guide/skeleton/body_and_arm_skin.py:</p>
<pre class="py-doctest">
skin = [
    (<span class="py-string">'body'</span>, (25, 91), <span class="py-string">'gil-cuerpo.png'</span>, True, True, 0.5),
    (<span class="py-string">'lower_arm'</span>, (0, 0), <span class="py-string">'gil-mano2.png'</span>, False, False, 0.5),
    (<span class="py-string">'upper_arm'</span>, (0, 0), <span class="py-string">'gil-brazo1.png'</span>, False, False, 0.5),
  ]</pre>
<p>The mess we have just created will look like this:</p>
<div class="figure">
<img alt="skeleton/body_and_arm_skin_pre.png" src="skeleton/body_and_arm_skin_pre.png" />
</div>
<p>We now have to use the editor to drag the parts until it looks like this:</p>
<div class="figure">
<img alt="skeleton/body_and_arm_skin_final.png" src="skeleton/body_and_arm_skin_final.png" />
</div>
<p>NOTE: When moving the control points, things look weird. Its because you are actually
only aplying a translation to the point. But the translation is then aplied over
the transformed point. It looks crazy, but you can get used to it if you play
with it for a while. And if you dont, you can just submit a patch.</p>
<p>It is important to move the bones, not just the skin, so the shoulder and elbow
move at the right locations. You can test that rotating the bones and making
sure that the images look good in all positions.</p>
<p>You then press the 's' key to save.</p>
<p>You should continue this way until you have the full skeleton and skin defined.</p>
<p>You can see and use the sample skeleton and skin provided in the test directory:</p>
<pre class="py-doctest">
tools$ python view_skeleton.py ../test/sample_skeleton.py

tools/skeleton$ python skeleton_editor.py ../../test/sample_skeleton.py ../../test/sample_skin.py</pre>
</div>
<div class="navigation navigation-footer container">
<span class="previous">Previous: <a class="reference" href="skeletal_animations.html" title="Skeletal Animations">Skeletal Animations</a></span><span class="next">Next: <a class="reference" href="animations.html" title="Animations">Animations</a></span><span class="breadcrumbs"><a class="reference" href="index.html" title="Programming Guide">Programming Guide</a> » <a class="reference" href="skeletal_animations.html" title="Skeletal Animations">Skeletal Animations</a> » Creating Skeletons ...</span></div>
</div>
</body>
</html>
